CanDo Accelerated Deck Editor


	How many times have you created a CanDo deck and then later
decided that there were some variables that should have been
named differently? Do you jump in and out of all the scripts
containing these variables and substitute the new names? Or do
you just forget it and leave the variable names unchanged? Do you
ever need to edit some CanDo code, but you just can't remember
where the code is? Would you like to put extensive comments in
your scripts during program development and have them
automatically removed from the final program? How about having
run-time control of things that are normally set at design time
such as object position and size? Well, you can have this and
more with a new software package available from Creative Logic
entitled CD_ADE. As the title of this article reveals, CD_ADE
means CanDo Accelerated Deck Editor. The name is a little
misleading in that CD_ADE does not have an editor included with
it. Rather, it provides a way for you to use your own editor to
modify CanDo decks. Let's take a tour of this program and see how
it can help you in your CanDo program development.

What is CD_ADE?
	CD_ADE is an Amiga program that can convert a CanDo deck
project file (the type of file saved and loaded by CanDo) to a
text file. It can also convert an appropriately formatted text
file into a CanDo project file. By converting a CanDo deck
project file to a text file, it can be loaded into your favorite
text editor or word processor for global editing of the deck
including card, window, and object definitions, as well as
scripts and routines. For example, it you have a variable named
LR that is used extensively throughout a deck, you can quickly
use the search and replace feature of your editor to change all
occurrences of LR to another name such as LowReal. I don't know
about you, but I have needed this feature many times. After
making changes to the text file, CD_ADE can then be used to
convert the modified text file back to a CanDo deck project file
that can be executed or loaded into CanDo. In order to execute
the deck, two files supplied by CanDo must be available,
DeckRunner and CanDo.library. DeckRunner is a program that CanDo
installs in the C: directory of the system disk. By setting the
default tool of the CanDo deck project file to DeckRunner, the
CanDo deck can be executed without using CanDo itself.
CanDo.library is the shared library file used by CanDo when
running a deck. Be aware that CD_ADE allows some modifications
to the text file that extends the capabilities of a CanDo deck
but makes it impossible to edit within CanDo. In these cases,
CD_ADE would be used as the final step in creating the program.
This will be discussed in more detail later.

What is Required to Run CD_ADE?
	The program documentation states that you need the following
Amiga environment to properly execute CD_ADE: CanDo 2.5x or
greater, AmigaDOS 2.0 or higher, minimum 512 KB fast memory, and
less than 100 KB of floppy or hard drive space. The main reason
for needing CanDo 2.5x is for access to DeckRunner and
CanDo.library. These files are not freely distributable and can
only be obtained legally as part of the CanDo package.
	You will probably find it easier to create your program with
CanDo and then use CD_ADE for editing and adding a few final
touches. However, this is not necessary. A text file containing
AV1 code can be created from scratch with an editor and then
converted with CD_ADE. AV1 is the underlying language used by
CanDo. In fact, it is the language with which CanDo itself is
written. AV1 code is a part of what you see when you print a deck
with ThePrinter utility. I use this utility to create the program
listings for my CanDo tutorial series.
	Although CD_ADE is suppose to work with CanDo 2.5x or
higher, I suspect that if an enhanced version of CanDo comes out
later, CD_ADE would not support any new features of the new
version. It would have to be upgraded also in order to handle the
new features.

How Does CD_ADE Work?
	CD_ADE and all its support files come on one floppy disk. It
is very simple to install on a hard drive. Just create a CD_ADE
directory and move all of the files from the floppy disk to this
directory. As stated earlier, CD_ADE can also be executed from a
floppy disk.
	When the CD_ADE program begins execution, it opens a window
on the Workbench screen (lower left of Figure 1). At this point
there are four ways you can pass a file to the program: drag and
drop a file icon into the CD_ADE window, select a file name from
a file requester, send a command to the CD_ADE ARexx port, or
execute the CD_ADE_AREXX CLI command. The latter method has the
added advantage that if CD_ADE is not currently running, it will
be started.
	When CD_ADE receives the name of a file to load, it checks
to see what type of file it is. If it is a CanDo project file, it
is converted to an AV1 text file. If it is an AV1 text file, it
is converted to a CanDo project file. Messages are displayed in
the CD_ADE window to let you know how it is proceeding. The
messages keep building up in the window until the tiny button
with a C in it (extreme lower right corner of the window) is
pressed.

What About the Details?
	To illustrate how CD_ADE works, I wrote a very simple
utility named CanDoTextReader using CanDo. The interface is shown
in the middle of Figure 1 and a listing generated by ThePrinter
utility is in Listing 1. The CanDoTextReader deck is quite small,
containing one card that has a memo object and a text button on
it.
	The card in this deck is named TextReader. Notice that the
window associated with the card has a resizing gadget in the
lower right corner. The card has a BeforeAttachment script that
does nothing but create a document named TextDoc. This document
is associated with the memo object which is named FileMemo.
	The text button is named SelectFile. It has an OnRelease
event script that opens a file requester, allows a file to be
selected, opens the file, determines it size, reads the file into
a string variable named TextVar, closes the file, clears the
document, types TextVar into the document, and then moves the
cursor to the top of the document. At this point, the contents of
the file will be shown in the FileMemo memo object.
	When the CanDoTextReader project icon is dragged to the
CD_ADE window, CD_ADE converts the project file to an AV1 text
file named CanDoTextReader.z (see Listing 2). This text file can
be loaded into an editor for modification. After changing the
file, it can be saved as CanDoTextReader.zi. When this file is
processed by CD_ADE, the old CanDoTextReader project file is
replaced with a new one based on the modified AV1 file. Also, if
any CD_ADE directives are added to the file that require text
substitution, the CanDoTextReader.z file is used as a work file
and is thus overwritten. If you do not wish for these files to be
overwritten, save the .zi file with a different name.

So What Can I Do With CD_ADE That I Can't Do With CanDo?
	Have you ever noticed that CanDo seems to be able to
perform tasks that it will not allow you to do in your own
programs? The reason for this is that CanDo does not give
programmers access to the full power of the AV1 language. By
working with the AV1 language directly in an editor and then
converting the AV1 file to a project file with CD_ADE, more of
the power of AV1 is opened up. To give you a small taste of this
power, I took the CanDoTextReader deck project file, converted it
to an AV1 text file, renamed it to CDADETextReader, modified it,
and then converted the modified file to a project file. The
CDADETextReader.zi file is shown in Listing 3. Before discussing
it, let's take another look at CanDoTextReader.
	As I pointed out before, the TextReader card's window has a
resizing gadget on it (see Figure 1). What happens when you
resize the window? Well, the window has an OnResized event
script. It simply moves the SelectFile text button to the bottom
center of the newly resized window using the MoveObject command.
However, there is a problem. When the button is moved, the
imagery of the old button does not go away. After resizing the
window several times, it will look something like Figure 2. The
only way to make the old imagery go away is to refresh the card
with a GotoCard command. But this creates another problem. The
window snaps back to its original design size rather than the
size you selected. The same thing happens if you move the window
to a new position and then refresh the card. You could try saving
the current position (WindowX and WindowY system variables) and
size (WindowWidth and WindowHeight system variables) of the
window in the OnResized script, reactivating the card, and then
positioning and sizing the window in the card's AfterAttachment
script using the MoveWindow and ResizeWindow commands. However,
the ResizeWindow command causes the OnResized script to execute,
which in turn reactivates the card, and so on forever. This means
flag variables have to be used. I tried several ways to
accomplish this and was never successful.
	In addition to the text button position problem, how do you
go about resizing the memo object when the window is resized?
After all, you are probably resizing the window so you can see
more text in the memo field. CanDo only allows you to set the
size of an object at design time. This information resides in the
definition area of an object.
	The solution to all the above problems is to use variables
for the window's position and size, the text button's position,
and the memo object's size. This is allowed by AV1 but cannot be
done within the CanDo programming environment.

How Does CDADETextReader Work?
	Look at the definition sections of the window, button, and
memo object in Listing 3. The variable names used for the
window's origin are WX and WY. The window's width and height are
stored in WW and WH. The button's X and Y positions use
calculated quantities involving the system variables WindowWidth
and WindowHeight. The same is true for the memo object's size.
Since all the variables representing the window's position and
size have an initial value of zero, they must be assigned
appropriate values before the window is displayed. The card's
BeforeAttachment script executes before the window is displayed
and is the ideal place to make the assignments. However, the
assignments should only be made once to prevent the window from
jumping back to its original position and size whenever the card
is reactivated. Thus, the assignments are only made when
Invocation is equal to zero. Afterwards, Invocation is assigned a
value of one to prevent the assignments from being made again.
Remember this little trick. It comes in handy quite a bit.
	When the window is resized, the OnResized event script
reassigns WX, WY, WW, and WH based on the current values of
WindowX, WindowY, WindowWidth, and WindowHeight, and then
reactivates the card. Since the window's position and size are
based on variables, rather than constants, the newly refreshed
card will maintain its new settings. Also, when the text button
and memo object are attached, they will be positioned and sized
based on the current window size. Figure 3 shows CDADETextReader
with its original position and size. The CDADETextReader.zi file
is displayed in the memo object. Figure 4 shows the window after
moving and resizing it. Isn't this GREEEEAAAAT? This
functionality could be useful in many applications.

What Else Can CD_ADE Do?
	Look at the first three lines of TextReader's
BeforeAttachment script. The first line is a regular CanDo
comment. However, the next two lines are CD_ADE directives. The
Let statement tells CD_ADE to insert the version information
after the semi-colon into the project file such that it can be
retrieved with the AmigaDOS Version command. CD_ADE will insert
the current date and time in the format YYMMDD.HHMMSS as well as
the version information. The documentation mentions that Version
seems to have a problem displaying more than 30 characters when
spaces are in the string. I had problems displaying any version
information regardless of size; only the date and time
information appears. I have not yet solved this problem.
	The comment statement containing the string "CD_ADE_Icons =
True" tells CD_ADE to create icons for the project file, the .z
file, and the .zi file. You can see these in the lower right of
Figure 1. There is one problem with the icon used for the project
file. It does not have a default tool of DeckRunner already set.
It must be set by the programmer. However, the icon file used for
project files resides in the Resources subdirectory of the CD_ADE
directory. It is named deck.info. By adding a default tool of
DeckRunner to this icon, all future project files will
automatically have this set.
	If the directive "; CD_ADE_NoComments = TRUE" is found in
an AV1 file, CD_ADE will remove all comments in the file before
creating a project file. This can be used to reduce the size of a
project file when the program is complete.
	CD_ADE also allows a ##INCLUDE statement to reside anywhere
within an AV1 file. It looks like this: ##INCLUDE
dh0:MyDir/MyFile. When this directive is encountered, MyFile is
inserted into the AV1 file. This allows generic reusable code to
be saved in a file and then included in any AV1 program that
needs it.
	Since AV1 is a hierarchical language (a deck has a card
which has objects), some interesting combinations can be dreamed
up. In AV1, a window can be a sub-object of a button object even
though CanDo does not allow this construct. The CD_ADE manual
warns that some combinations do not work and encourages the
programmer to experiment. Also, cards can have multiple windows
rather than the one allowed by CanDo. As a novice BASIC
programming instructor I had in college used to say, "Try it and
find out. Try it and find out."

Is CD_ADE Worth Buying?
	CD_ADE can be obtained directly from Creative Logic for
$49.95 + $3.00 S&H. I learned of the program in an advertisement
in the pages of this magazine (AC 9.4, p. 69). I mailed my check
and received the software in exactly two weeks. The CD_ADE
program, support files, and manual are on one disk. No printed
manual comes with the package. A second disk contains an AV1
program named WordCross. This program can be used to examine
some of the techniques available in AV1. If you are a moderate to
heavy user of CanDo, I believe you will want a copy of CD_ADE.
Of course, it is possible that a future release of CanDo will
have some of the features of CD_ADE, but CD_ADE is available now,
and there are no guarantees concerning new features in later
releases of CanDo.
	So what are you waiting for? Write that check and send it
to:

	Creative Logic
	Attn: CD_ADE
	POB 743271
	Dallas, TX  75374-3271
	Phone: (214) 432-9824
	Fax: (214) 393-0007
